Skunkware 5

home *** CD-ROM | disk | FTP | other *** search

/ Skunkware 5 / Skunkware 5.iso / man / cat.1 / xc.1 < prev next >

Wrap

Text File | 1995-07-26 | 50.1 KB | 1,321 lines

XC(L) XENIX/UNIX (printed 3/11/94) Name xc - communications program Syntax xxxxcccc [----lllldevice] [----ssssscript | ----tttt] Description XXXXcccc calls out over a serial port to another computer. It can manage an interactive session or be called from ccccrrrroooonnnn(C). It has various means for transferring files between computers, and can be partially or totally under the control of scripts. XXXXcccc starts up by reading the file ._x_c, which is sought for in this order: in "XC_PATH", in the current directory, in your _H_O_M_E directory, or in a default directory defined at compile time. This startup file may contain any of the valid _S_E_T commands described below. XXXXcccc then displays the current settings, and presents an <_X_C> prompt, unless either the ----tttt or ----ssss option was present. _O_p_t_i_o_n_s ----llll_d_e_v_i_c_e Use the specified _d_e_v_i_c_e, which need not be the full pathname, e.g. "/dev/tty1A" or "tty1A" are equally acceptable. The line could either be directly connected to another computer, or have a modem on it. In either case (if a value was defined for DIDO at compile time), xxxxcccc attempts to suspend a ggggeeeettttttttyyyy(M) pro- cess that might be on that line, and then use the uuuuuuuuccccpppp(C) _L_C_K.._f_i_l_e mechanism to lock the line. ----ssss_s_c_r_i_p_t Execute the specified _s_c_r_i_p_t after program startup. ----tttt Go directly to terminal mode. The default is to go to command mode on program startup. This option is incompatible with the ----ssss option. _E_n_v_i_r_o_n_m_e_n_t If the environment contains a variable called "MODEM", then the value of that variable will be the default device. As with the ----llll flag, this need not be the full pathname. To set such a variable, in the Bourne shell, you might say: MODEM=tty01; export MODEM or, in the C shell, setenv MODEM tty01 If the environment contains a variable called "BYEttyxx", where "ttyxx" stands for the basename of the modem line selected either by the MODEM variable or by the "-l" command option, then the value of that variable will be sent to the modem when the program terminates. This is useful for setting the modem back to some preselected state. Example: BYEtty01=ATZ ; export BYEtty01 Whatever string is contained in the "Byexxxxx" variable will be sent to the modem preceded and followed by a carriage-return. Newer modems can be preset to revert to a predetermined state when the DTR signal of the computer is dropped, and so would not need to avail themselves of this feature. Furthermore, ggggeeeettttttttyyyy programs which have been suspended, and which restart as xxxxcccc exits, will reset a modem using dialers or chat scripts referred to in the /usr/lib/uucp/Devices file. The environment may contain a variable called "XC_PATH", consisting of colon separated absolute paths to directories. If this variable is set to, say, "/usr/joe/xc:/usr/lib/xc", then those two directories are the first places searched for any scripts. _C_o_m_m_a_n_d _M_o_d_e When entering characters in command mode (that is, at the <_X_C> prompt), control characters echo as ^x, where "x" is the control character that was entered. Backspacing (using whatever key is defined in the current environment) backspaces over both positions of the displayed control character, as expected. An "interpreted" key can be added in a manner similar to that of vvvviiii(C); simply type ^V followed by the character to insert (backspace, delete, carriage return, or newline). The following commands are available at the <_X_C> command prompt: cccc cccciiiissss Respond to an ENQ signal for a CIS B-Plus protocol transfer. This command is used for both uploading and downloading from CompuServe. dddd ddddiiiiaaaallll Enter the dial directory. Returns to the <_X_C> prompt if exited without dialing, but returns to terminal mode after dialing or running a script. ssss _f_i_l_e ssssccccrrrriiiipppptttt _f_i_l_e Execute _f_i_l_e, which contains appropriate xxxxcccc script com- mands. Returns to terminal mode when the script is com- plete. rrrrbbbb _f_i_l_e (XMODEM binary receive) rrrrtttt _f_i_l_e (XMODEM text receive) Receive _f_i_l_e from the remote sys- tem. ssssbbbb _f_i_l_e (XMODEM binary send) sssstttt _f_i_l_e (XMODEM text send) Transmit _f_i_l_e to the remote system. sssseeeetttt [_o_p_t_i_o_n_s] Display or set the transmission parameters used by xxxxcccc. See below. tttt tttteeeerrrrmmmm Enter terminal mode. xxxx qqqq eeeexxxxiiiitttt qqqquuuuiiiitttt Exit program. Return to invoking program/shell. hhhh hhhhaaaannnngggguuuupppp Hang-up the modem. %%%%pppp _l_o_c_a_l__n_a_m_e [_r_e_m_o_t_e__n_a_m_e] Transmit (put) a file to a remote Unix system. This command uses standard Unix utilities on the other end. _R_e_m_o_t_e__n_a_m_e defaults to the same pathname as _l_o_c_a_l__n_a_m_e if not otherwise specified. %%%%tttt _r_e_m_o_t_e__n_a_m_e [_l_o_c_a_l__n_a_m_e] Receive (take) a file from a remote Unix system. This command uses standard Unix utilities on the other end. _L_o_c_a_l__n_a_m_e defaults to the same pathname as _r_e_m_o_t_e__n_a_m_e if not otherwise specified. ???? hhhheeeellllpppp Displays a brief summary of xxxxcccc commands, the SET options, and terminal-escape commands. [Note: a compile-time option can disable the following three options to prevent any access to shells or other programs outside of xxxxcccc.] !!!! _c_o_m_m_a_n_d Execute the specified _c_o_m_m_a_n_d as a child process. If _c_o_m_m_a_n_d is omitted, execute a local interactive shell. (A space is required between the !!!! and the _c_o_m_m_a_n_d.) !!!!!!!! Re-execute the last shell command string. $$$$ _c_o_m_m_a_n_d Execute a shell _c_o_m_m_a_n_d with stdin and stdout redirected to the modem port. This effectively puts the computer into a "host" mode. (A space is required between the $$$$ and the _c_o_m_m_a_n_d.) _U_s_i_n_g _t_h_e _S_E_T _C_o_m_m_a_n_d The _S_E_T command is used to display and set/reset xxxxcccc's tunable parame- ters. Any of these commands may be placed in the ._x_c file which is read upon starting up xxxxcccc. Used alone, _S_E_T displays xxxxcccc's current parameters. The following parameters can be set (note that except in the case of _n_a_m_es, these commands are case-_i_nsensitive, and that there alternative forms of the commands shown on the XC help screen): set auto on|off Sets the auto-capture feature. When entering terminal mode, capturing commences without the necessity to manually request it. set bps _v_a_l_u_e set baud _v_a_l_u_e Set the desired bits/second rate. Supported bps rates are 300, 1200, 2400, 9600 (and, if included at compile time, 19200 and 38400). set cfile _n_a_m_e Set the _n_a_m_e of the capture file. set cis on|off Set response to a CompuServe file transfer request (<ENQ>). An "on" value specifies that when in terminal mode, an <ENQ> character will launch a CIS B-Plus pro- tocol transfer. This parameter should be set "off" when not connecting to CompuServe, as phone line noise may cause a bogus file transfer request. set cr on|off In uploads using B-Plus protocol, setting this option "on" will insert a carriage-return after each newline in an ASCII file. If you expect your ASCII upload to be captured by DOS users, it is best to set cr "on". If your ASCII upload is meant strictly for Unix users, then you may set cr "off". The B-Plus protocol imple- mentation used by xxxxcccc will always strip end-of-line carriage-returns from incoming ASCII files. set dir _n_a_m_e Set the current working directory. set menu on|off By default, a one-line menu is displayed above the <_X_C> prompt to remind the user of options most fre- quently chosen at this point: "[d]ial directory [t]erminal mode [q]uit [s]cript [?]help". Setting the option "off" turns off this display. set nl on|off If this option is set "on", then newlines are sent as carriage-returns. If this option is set "off", then newlines are sent as newlines (carriage-returns are in any case always sent as carriage-returns). This option applies to input from the keyboard, or from a disk file using the "XXXXCCCCAAAAPPPPEEEE FFFF" facility or a script "type" command (See below). This option has no effect on built-in XMODEM or B-Plus protocol transmissions, and has no effect on incoming data. set pfile _n_a_m_e Set the _n_a_m_e of the phone directory. set proto _v_a_l_u_e This refers to the serial port character protocol, not to a file transfer protocol. The possible values are 8N, 7E, or 7O, (case insensitive) which respectively set the modem port to a character size of 8 with no parity, or a character size of 7 with either even or odd parity. During B-Plus or XMODEM transfers, the port protocol is set to 8N, and reverts to its prior setting thereafter. set xcape _c_h_a_r set escape _c_h_a_r Set the XXXXCCCCAAAAPPPPEEEE character (see below) to _c_h_a_r. This should be set to some non-printing character (other than backspace, tab, newline, of course). The charac- ter may be entered by depressing the Control key first and then typing a letter, or by typing a carat (^) followed by a letter. set xon on|off set xoff on|off Set XON/XOFF flow control flag. If "on", the program will honor the XOFF control character and wait until an XON character is received before transmitting any more information. If "off", the program will ignore XOFF/XON requests. _T_e_r_m_i_n_a_l _M_o_d_e In terminal mode, all characters typed at the keyboard are sent to the modem, except that newline characters (0x0A) are translated to carriage-returns (0x0D) when you have "set nl 'on'"; all characters received from the modem are displayed on the local terminal screen. XXXXCCCCAAAAPPPPEEEE is a key that will, when typed in terminal mode, introduce an xxxxcccc "escape" command. Don't confuse XXXXCCCCAAAAPPPPEEEE with the <ESCAPE> key. The default definition for XXXXCCCCAAAAPPPPEEEE is ASCII 1, or Control-A. It can be rede- fined at run time with the "set escape _C" command (or it can be rede- fined in the ._x_c startup script). When the XXXXCCCCAAAAPPPPEEEE key is typed in terminal mode, the program will examine the next key pressed. If this key has been "bound" to perform a certain function, that function will be performed; otherwise, the second char- acter is sent to the modem. Thus, to send the XXXXCCCCAAAAPPPPEEEE character through the modem, it is necessary to press the key TWICE. Thus the ESCAPE key itself would be a terrible choice for XXXXCCCCAAAAPPPPEEEE, because it is used so often by other programs: if you were logged into a remote system and running, say, vvvviiii, it would be a great annoyance to have to hit ESCAPE twice to get it transmitted once. The following keys (case _i_nsensitive) are bound at startup time. Others may be added through the binding commands available in xxxxcccc scripts. Command Function Description XXXXCCCCAAAAPPPPEEEE //// Help Display the table of bound keys XXXXCCCCAAAAPPPPEEEE ???? Help Display the table of bound keys XXXXCCCCAAAAPPPPEEEE bbbb _BREAK Send a MODEM BREAK signal (a sustained null). XXXXCCCCAAAAPPPPEEEE dddd _Directory Display the phone directory. XXXXCCCCAAAAPPPPEEEE ffff _File Send a file through the modem (ASCII transfer). XXXXCCCCAAAAPPPPEEEE ssss _Script XXXXcccc will request the name of a script to execute. XXXXCCCCAAAAPPPPEEEE hhhh _Hangup Tell the modem to go on-hook. XXXXCCCCAAAAPPPPEEEE yyyy Capture _Yes Open the capture file in APPEND mode (text received over the port accumulates at the end of the file). If the file is already open, a mes- sage is printed to that effect. XXXXCCCCAAAAPPPPEEEE nnnn Capture _No Close the capture file. If it wasn't open, a message of regret is printed. XXXXCCCCAAAAPPPPEEEE xxxx e_Xit Exit terminal mode back to _<_X_C_> command mode. XXXXCCCCAAAAPPPPEEEE qqqq _Quit Quit xxxxcccc altogether. _P_h_o_n_e_l_i_s_t XXXXcccc looks for a ._p_h_o_n_e_l_i_s_t file in the following order: in the current directory, in your home directory as defined by the $HOME environment variable, or in the LIBDIR as defined at compile time in _x_c._h. However in command mode, any filename can be substituted, using the SET PFILE command, so long as it has the following characteristics: It is ASCII text (lines of text separated by newlines). The first field of data in each line (after any whitespace and up to the next occurence of whitespace) is a phone number in a valid format for the modem being used. Descriptive text may follow the phone number. Spaces may be included in this text, but a <TAB> must terminate this text. The following three definitions may then follow in any order: PROTO=sss (sss=7e|7o|8n) Set the serial port protocol for 7-bit char- acters with either even or odd parity, or for 8-bit charac- ters with no parity. BPS=nnnn (n=300|1200|2400|9600|19200|38400) Set the bits/second rate to the specified value. SCRIPT=file Immediately after sending the autodial string, execute the script file specified. (Note that the specified filename is CASE SENSITIVE!) The following definition, if used, must be the LAST field on the line. PREFIX=xxxxxxxx (e.g., PREFIX=ATs110=0s111=0) The PREFIX="string" allows you send your modem a different setup string for each situation (default: no special setup). This is helpful for MNP and Telebit modems which require special attention for contacting non- MNP modems and other Telebits. _S_c_r_i_p_t_s The xxxxcccc script language is intended to be closely similar to the Unix Bourne shell language. Unfortunately, it isn't identical to the Bourne shell, so it has the same problem that the aaaawwwwkkkk(C) program does for those experienced in the C language: an aaaawwwwkkkk script LOOKS like C, but it isn't, really; and in the same way, an xxxxcccc script LOOKS like a Bourne shell script, but isn't. So the operation of the Bourne shell, if you're familiar with it, is useful as an analogy in understanding the xxxxcccc script language, but only as an analogy. An xxxxcccc script consists of lists of commands. Commands are set off from each other within a list by either a newline ('\n') or a semicolon (;), as is the case with the Bourne shell. The semicolon and the newline have identical effect as command separators, so (anticipating a bit here) you could say either if counter morethan 5 then transmit "bye^M" quit endif or if counter morethan 5; then transmit "bye^M"; quit; endif and the result will be the same either way. The newline and the semi- colon are treated the same way as in the Bourne shell, except that a newline cannot be quoted so as to remove its interpretation as a com- mand terminator (in other words, a quoted string cannot contain a new- line). Commands are composed of _w_o_r_ds separated by spaces or tab characters, and a _w_o_r_d can be one of the following: * One of the xxxxcccc script language keywords, which are listed below, with appropriate explanations. * A number, meaning a sequence consisting only of digits, with an optional leading minus sign to indicate a negative number. * A literal string of characters surrounded by double-quotation marks ('"'); such a string can be no longer than 80 characters. A double- quotation mark can be imbedded within the string by preceding it with a backslash ('\"'); when the string is interpreted, the backslash is disregarded and the double-quotation mark is treated as part of the string. Mismatched quotation marks result in a syntax error. * The name of a user variable, which can have either a string or a numeric value. The name of a user variable must begin with an alphabetic character. * The name of a shell environment variable, preceded by a dollar sign ('$'). The xxxxcccc script language examines the Unix environment for the specified variable and, if such a variable exists, substitutes the value of that variable. The result is treated as if it were a quoted literal string, and, therefore, should not be more than 80 charac- ters long, or else it will be truncated to its first 80 characters. Similarly, such an environment variable should not contain a new- line. * An expression surrounded by back-quotation marks ('`'). This sort of expression operates similarly to the Bourne shell's command-substi- tution mechanism: the contents of the back-quotes are passed to the Bourne shell, and the standard output of the back-quoted command is treated as if it were a quoted literal string. Therefore, the command's output should not be more than 80 characters long, nor contain a newline. Also, the contents of the back-quotes cannot be longer than 80 characters, nor contain a newline. * An expression introduced by a pound-sign (or number-sign: '#'), which is treated as a comment. All characters from the '#' until the end of the physical line are ignored. This comment mechanism is the same as in the Bourne shell. * A limitation of the script language is that only one character string can be passed as an argument to any of the script commands. The _b_i_n_d__f_u_n_c_t_i_o_n, _b_i_n_d__s_c_r_i_p_t, and _b_i_n_d__s_t_r_i_n_g commands thus need to use a decimal digit to represent the key that is to be bound. The ASCII value of the the key is employed. As an example, Control-C is identified as 3, Control-Z is 26, the ESCAPE key is 27, a space is 32, the number "1" is 49; letters are case-_i_nsensitive so that iden- tifying the bound key as "65" or as "97" will always bind _b_o_t_h "a" and "A" to the same command. Quoted literal strings (and the two other mechanisms that act like quoted literal strings, shell environment variables and back-quoted shell commands) may be up to 80 characters long. All other words must be no longer than 16 characters, and are treated case-independently (which is to say, uppercase is the same as lowercase); note, though, that the names of shell environment variables are case-dependent (uppercase must match uppercase and lowercase must match lowercase), because they are case-dependent in the shell. Any word not recognizable within the foregoing categories is treated as the name of a new user variable. Such a word, if longer than 16 charac- ters, is considered to be a syntax error. User variables are created with the 'assign' script keyword, and may have either numeric or string values. The type of a user variable is determined by how it's created; if it's assigned to a string, it's a string variable, and if it's assigned to a number, it's a numeric vari- able. The value of any user variable can be changed with another 'assign' command, and numeric variables can be changed to string vari- ables and vice-versa. Shell environment variables cannot be changed within an xxxxcccc script, but the value of a shell environment variable can be assigned to a user variable, and the value of the user variable can thereafter be changed. Scripts are contained in ASCII text disk files, one script to a file. A script can invoke another script as a subroutine with the 'call' key- word; up to 5 scripts can be nested in this way at any single time. With all this said, the following list of xxxxcccc script language commands should be comprehensible. The format "<something>" means that a token, or word-type, of the "something" type is meant rather than the literal sequence 'something'. _S_c_r_i_p_t _L_a_n_g_u_a_g_e _C_o_m_m_a_n_d_s Note that all the commands are case-_i_nsensitive! _a_f_f_i_r_m Syntax: affirm Reads a string from the terminal, and returns TRUE if the string begins with 'y' or 'Y'; otherwise, returns FALSE. Used in evaluat- ing conditional expressions. The string must be terminated by a newline or carriage-return. Example: echo -n "Continue (y/n)? " if affirm then continue else break endif _a_s_s_i_g_n Syntax: assign <varname> eq <number> assign <varname> eq "string" assign <varname1> eq <varname2> assign <varname> eq <script-command> Assigns to user variable <varname> the value following "eq"; if that value is a number, then <varname> becomes a numeric user vari- able; if that value is a string, then <varname> becomes a string user variable. If <varname> does not already exist as a user vari- able, it is created. Variable space is allocated dynamically, but running out of memory space for variables is unlikely. All vari- ables are global across scripts that run at the same time via the 'call' keyword, and all variables vanish when a script, called directly from xxxxcccc as opposed to called from another script, exits. In other words, variable values are not static except during 'call' execution. Variable names cannot be longer than 8 characters. Suc- cessive 'assigns' are permissible, and the type of the variable changes according to the type of the value following "eq". A user variable is destroyed with the 'unassign' keyword. If a variable is assigned the value of a script command, then it becomes a numeric variable with value TRUE or FALSE, depending on the status returned by the script command. If a variable is assigned the value of a back-quoted command, it becomes a string variable with the value of the first 80 characters of the back- quoted command. If a variable is assigned equal to an environment variable, it becomes a string variable with the value of the first 80 characters of the value of the environment variable. Examples: assign numvar eq 5 assign strvar eq "This variable is a string" assign mydir eq $HOME assign numvar2 eq numvar assign strvar2 eq strvar assign numvar eq true assign today eq `date`; echo "today is " today _b_e_e_p Syntax: beep Sends a Control-G to the terminal. Useful for alerting the user that some event has occurred, for example a CONNECT after a lengthy redialing session. _b_i_n_d__f_u_n_c_t_i_o_n Syntax: bind_function _c_o_d_e "function" Bind the character identified by the number specified by _c_o_d_e to the xxxxcccc builtin function "function". The "function" may be one of the following (case is ignored): BRKCHAR Send modem BREAK signal CAPTEND Turn off terminal mode capture CAPTYES Turn on terminal mode capture DIALCHR Dial from phonelist DIVCHAR Send file through modem DOSCRPT Execute script file (prompts interactively) EMITSTR Emit string ENDCHAR Exit terminal mode HLPCHAR Display terminal mode key bindings HUPCHAR Hang up modem QUITCHR Quit program SCRPCHR Prompt for script file Example: bind_function 26 "quitchr" This binds Control-Z to quit the XC program. _b_i_n_d__s_c_r_i_p_t Syntax: bind_script _c_o_d_e "scriptname" Bind the character identified by the number specified by _c_o_d_e to execute the script named by "scriptname". Upon termination of the script, the program will resume terminal mode, unless the "quit" script function was executed. Examples: bind_script 18 "/usr/lib/xc/.rz" This binds Control-R to execute the script /usr/lib/xc/.rz. The .rz script supplied with the source code contains: tty "on" echo -n "What files are to be received? " read FILES transmit "sz -y " transmit FILES transmit "^M" echo "Starting ZMODEM Receive (rz -y)" pipe "rz -y" Pressing XXXXCCCCAAAAPPPPEEEE ^^^^RRRR will ask for some file name(s), and start an sssszzzz command on the remote system, and an rrrrzzzz on the local system to receive the file(s). bind_script 19 "/usr/lib/xc/.sz" This binds Control-S to execute the script /usr/lib/xc/.sz. The .sz script supplied with the source code contains: tty "on" echo -n "What files are to be sent? " read FILES echo "Starting ZMODEM send (sz -y " FILES ")" pipe "sz -y " FILES Pressing XXXXCCCCAAAAPPPPEEEE ^^^^SSSS will ask for some file name(s), and then launch sssszzzz on the current system. SSSSzzzz will itself start an rrrrzzzz process on the remote system. _b_i_n_d__s_t_r_i_n_g Syntax: bind_string _c_o_d_e "string" Bind the character identified by the number specified by _c_o_d_e to emit the string specified by "string". The string is sent to the modem untranslated; eg, it is not exam- ined for embedded terminal mode escapes. Example: bind_string 49 "AAATZ^M" This binds "1" to send the sequence to reset the modem. _b_r_e_a_k Syntax: break Exits from the immediately enclosing 'while' loop. Identical to the C language 'break', and to the Bourne shell 'break' except that the xxxxcccc script language 'break' does not take a numeric argument. Don't confuse this with the script keyword 'xmitbrk', which sends a BREAK signal to the modem port. _c_a_l_l Syntax: call "scriptname" Suspends execution of the current script, and attempts to load and run the specified scriptname. The scriptname must be a quoted literal string. There is no xxxxcccc analogue of the Bourne shell "exec" command; all subscripts in xxxxcccc are treated as sub-routines. All variables are global across subscripts, so if a subscript changes the value of a variable, then that change will remain in effect after return to the parent script. Shell environment variables can- not be changed by any xxxxcccc script. _c_a_p_t_u_r_e Syntax: capture "on" capture "off" Turns the file-capture function on or off. Note that the arguments must be quoted literal strings. Note also that when the script exits into terminal mode, the file-capture function is turned off. If you have 'set auto "on"', then you will begin capturing immedi- ately upon entering, or returning to, terminal mode. If not, then you must manually type "XXXXCCCCAAAAPPPPEEEE YYYY" to start capturing when entering terminal mode. _c_o_n_t_i_n_u_e Syntax: continue Resumes execution at the top of the immediately enclosing 'while' loop. Identical to the C language 'continue' instruction, and to the Bourne shell 'continue' command except that no numeric argument is accepted. _d_e_b_u_g Syntax: debug "on" debug "off" If the 'debug' option is on, then xxxxcccc will make many parenthetical comments about what it's doing while it runs the script. These com- ments can sometimes be helpful in debugging script logic. Note that the argument must be a quoted literal string. While debugging a script containing a password, turn this option off, then on again, to reduce the excitement-level of any col- leagues collected circa your screen. _d_e_c_r Syntax: decr <numeric-variable> Decrements the value of the specified numeric user variable by 1. Useful in controlling loop execution. If the specified variable isn't numeric, or doesn't exist, a syntax error results. _d_i_a_l Syntax: dial "number-string" Dials the specified number, using modem-command strings defined in xc.h. The number should not contain spaces; dashes are acceptable. _e_c_h_o Syntax: echo "string" <variable> ... echo -n "string" <variable> ... This command sends its arguments to the user's terminal. The number of arguments is optional, except that the total result may not exceed 80 characters. Variables and back-quoted shell commands are expanded as necessary. If the "-n" switch is present, then no carriage-return/newline sequence is appended to the output. Examples: echo "The time and date are now " `date` echo "My terminal type is " $TERM echo "My terminal type is " $TERM " today." Note that whitespace isn't echoed unless it's part of a quoted literal string. _e_x_i_t Syntax: exit Terminates execution of the current script. If a script reaches its end, it exits automatically, so 'exit' is useful mainly to ter- minate a script prematurely. _f_a_l_s_e Syntax: false Same as the Unix 'false' command. Does nothing, but returns a FALSE status value. Useful within conditional expressions. Example: if waitfor "CONNECT" 30 eq false then quit endif Note that above example could be rewritten using the negating modifier "!": if ! waitfor "CONNECT" 30 then quit endif and note too that the "!" must be separated from its argument by whitespace. _f_i_l_e Syntax: file <script-command> The standard output of the specified script command is sent to the current capture file. If the "capture" option is not set, then an error message is displayed, but script execution continues. Examples: file echo "--------- CUT HERE ----------" Sends the output of the 'echo' command to the current capture file, provided that the "capture" option is now "on". file echo `date` Sends a timestamp to the current capture file, provided that the "capture" option is now "on". The same thing could have been done with file shell "date" _h_a_n_g_u_p Syntax: hangup Tells the modem to go on-hook. _i_f Syntax: if <list1>; then <list2>; [ else <list3>; ] endif If <list1> evaluates as TRUE, performs <list2>; otherwise, if <list3> is specified, performs <list3>; then resumes execution immediately following 'endif'. To accommodate those whose minds wander while writing scripts, 'fi' is an acceptable synonym for 'endif'. Each list may consist of any number of script commands separated by semicolons or newlines. The value of <list1> is determined by inclusively OR'ing the value of each directive in the list, so that if any of the directives in <list1> evaluates as TRUE, then so will <list1>. <list1> is performed in its entirety regardless of the value of any of its component commands. The keywords 'then', 'else', and 'endif' (or 'fi') must be immedi- ately preceded by command separators, either a semicolon or a new- line, just as is the case in the Bourne shell. For conditional evaluation in 'if' and 'while' constructions, the following comparators are available in addition to the script directives mentioned elsewhere: <varname1> eq "string" <varname1> eq <number> <varname1> eq <varname2> <varname1> "string" evaluates as TRUE if the value of user variable <varname1> is the same as that of a specified string or numeric constant or of a specified second variable name. If the variable name <varname1> is not followed by anything else, then the expression evaluates as TRUE if the variable is numeric and has a non-zero value, or if the variable is a string variable and has a non-zero length; otherwise, the expression evaluates as FALSE. Comparing a string variable to a numeric variable, or vice-versa, causes a syntax error. If a conditional expression consists only of a quoted literal string, the expression evaluates as TRUE if the string's length is non-zero, and otherwise evaluates to FALSE. Because environment variables and back-quoted shell commands are treated as if their output/value were quoted literal strings, this allows direct test- ing of a shell command or of an environment for non-zero length. Nonexistent environment variables are treated as if they exist with the value "" (a string of zero length). <varname1> neq "string" <varname1> neq <number> <varname1> neq <varname2> evaluates as TRUE if the value of user variable <varname1> is not equal to that of a specified string or numeric constant or of a specified second variable name. Comparing a string variable to a numeric variable, or vice-versa, causes a syntax error. <varname1> lessthan "string" <varname1> lessthan <number> <varname1> lessthan <varname2> evaluates as TRUE if the value of user variable <varname1> is less than that of a specified string or numeric constant or of a speci- fied second variable name. String variables are compared lexically according to ASCII value. <varname1> morethan "string" <varname1> morethan <number> <varname1> morethan <varname2> operates identically to 'lessthan', except in reverse. The value of any conditional expression may be negated by preceding it with an exclamation point followed by a space or tab. Examples: if counter eq 0; then break; endif; if var1 eq var2; then echo "identical"; endif if counter morethan 20; then break; endif; if counter lessthan 0; then break; endif; if ! counter; then echo "counter is " counter; endif To perform a list if any of a set of conditions exist: if counter morethan 5; counter eq brkvalue; # a second comparator then break; endif; i.e., perform the 'break' directive if the value of numeric user variable 'counter' is greater than the numeric constant 5, or if the value of 'counter' is equal to that of the user numeric vari- able 'brkvalue'. _i_n_c_r Syntax: incr <numeric-variable> Increments the value of the specified numeric user variable by 1. The opposite of 'decr'. _l_i_n_k_e_d Syntax: linked 'linked' is a pseudo-function that evaluates as TRUE if the current script has been invoked from the dialing directory, and as FALSE otherwise. Example: if ! linked; then dial "5551212" endif _p_a_u_s_e Syntax: pause <number> Suspends execution for the specified <number> of SECONDS. Identical to Unix "sleep." _p_i_p_e Syntax: pipe "<shell-command>" The standard input and standard output of the specified shell com- mand are connected to the modem port, and the command is executed. This is the equivalent of the command mode "$" command. Examples: pipe "echo \"\177\"" sends a DELETE character to the modem. pipe "rz" performs a file receive via ZMODEM, assuming that Chuck Forsberg's 'rz/sz' programs reside on your system. _p_o_r_t_n_a_m_e Syntax: portname This isn't a command, but a synonym for the current modem terminal device, treated as if it were a quoted string. Useful if modems of differing types are attached to different terminal lines and need different dialing or initialization sequences. To compare the value of 'portname' to some other string, you must first assign a user variable equal to 'portname'. Examples: assign myport eq portname if myport eq "/dev/tty01" then transmit "AT&E0^M" endif _q_u_i_t Syntax: quit Exits the script and terminates xxxxcccc entirely. Any LCKfile will be removed if possible and the user's terminal will be restored to the state it was in when xxxxcccc was invoked. _r_e_a_d Syntax: read <variable-name> Takes a string from the user's keyboard and places it into the specified user variable. Any previous value of the specified vari- able is discarded. _r_e_d_i_a_l Syntax: redial Redials the number most recently dialed with the 'dial' command. _s_e_e_n Syntax: seen "string" <number> Evaluates as TRUE if "string" has occurred within the last <number> characters received during the most recent 'waitfor' command. Only up to 2048 characters are remembered at any one time during 'wait- for' processing. If no <number> is specified, then all the charac- ters received during the most recent 'waitfor' command are exam- ined, up to a maximum of 2048. The 'seen' buffer is reset at the beginning of each 'waitfor' command. This is useful to tell which of several strings has been received. Example: if waitfor "string1" 20 then echo "Received 'string1'." else if seen "string2" then echo "Received 'string2' instead." endif endif _s_e_t Syntax: set <xxxxcccc-set-option> <value> This command is the same as the command-mode xxxxcccc 'set' command, such as "set bps 1200", "set cis on", and so forth, except that a string <value> must be enclosed within double-quotation marks. Examples: set cis "on" set cfile "newfilename" set auto "on" set bps 2400 _s_h_e_l_l Syntax: shell "<shell-command>" The shell command enclosed within the double-quotation marks is executed. This is similar to the xxxxcccc command-mode "!" command. Remember that if the shell command contains double-quotation marks, they must be escaped with backslashes. _t_i_m_e_o_u_t Syntax: timeout <number> If <number> is greater than zero, starts a timer which will cause the MOST DEEPLY NESTED script to exit when <number> of MINUTES expire. If <number> is zero, then any pending timeout is cancelled. If <number> is negative, nothing happens. Expiration of the specified timeout causes the most deeply nested script to exit, not to terminate xxxxcccc. To cause the program to quit if a timeout expires, use a subscript. Example: 'script1' contains: call "script2" if expired then quit endif # more commands 'script2' contains: assign expired eq 1 timeout 5 # limit of 5 minutes while ! waitfor "login:" 30 do xmitbrk done assign expired eq 0 exit When 'script2' exits, the numeric variable 'expired' will be set to 1 if 'script2' timed out, and will be 0 otherwise. 'script1' can act on this information accordingly. _t_r_a_n_s_m_i_t Syntax: transmit "string" Sends a string to the modem. The string is sent with brief pauses between characters, to accommodate modems that cannot accept rapid command input, and within the string, any alphabetic character pre- ceded by a caret (^) is translated to the corresponding Control- character. Example: transmit "ATDT 5551212^M" sends the string "ATDT 5551212" to the modem, followed by a carriage-return character. _t_r_u_e Syntax: true Does nothing, but always evaluates as TRUE. Useful in conditional expressions. The opposite of 'false'. _t_t_y Syntax: tty "on" tty "off" Ordinarily, during script execution, characters received from the modem port are echoed to the user's terminal screen. This happens only during 'waitfor' and 'type' execution, so it may be a bit choppy. This echoing can be turned off with tty "off" and turned back on with tty "on" Note that "on" and "off" must be enclosed in quotation marks. _t_y_p_e Syntax: type "<filename>" Sends the specified ASCII file to the modem port. This is the same as the xxxxcccc terminal-mode "send ASCII file" escape. _u_n_a_s_s_i_g_n Syntax: unassign <variablename> Erases the specified user variable. The variable may be either numeric or string type. The variable name must not be enclosed in quotation marks, because variable names are considered to be xxxxcccc script keywords, and not literal strings. _w_a_i_t_f_o_r Syntax: waitfor "string" <number> Scans input from the modem port for an occurrence of the specified string, which must be enclosed in quotation marks. The scanning continues for the specified <number> of SECONDS or until the speci- fied string is identified in the modem input stream, whichever comes first. This command evaluates as TRUE if the specified string is found, and as FALSE if the specified <number> of SECONDS elapses and the string isn't found within that time. The default time, if no <number> is specified, is roughly 30 seconds. String matching is performed on a case-_i_nsensitive basis. Within the string, any alphabetic character preceded by a caret (^) is translated to the corresponding Control-character. Examples: assign counter eq 1 while ! waitfor "login:" 15 do xmitbrk; incr counter; if counter morethan 5 then quit endif done If in a CompuServe Forum the "prompt character" has been set by the user to be a backspace, this test will log off if the main prompt is not seen in the next sixty seconds: if ! waitfor "forum !^H" 60 then transmit "bye^M"; quit endif If the 'cis' option has been set to "on", either in the ._x_c startup script, or by a direct 'set' command from command mode, or with set cis "on" within a current script, and if during 'waitfor' processing a CIS B-Plus protocol file transfer request is received, then the B-Plus protocol transfer is performed, the <number> argument is reset to its original value, and 'waitfor' processing continues. This allows automatic B-Plus protocol file transfers from within a script. _w_h_i_l_e Syntax: while <list1>; do <list2>; done Operates similarly to the 'if' command, except that <list2> is exe- cuted repeatedly so long as <list1> evaluates as TRUE. All the con- ditional comparators and rules for comparisons that apply for the 'if' command also apply to 'while'. (Note that 'while' loops can be nested within 'if' commands and vice-versa.) _x_m_i_t_b_r_k Syntax: xmitbrk Sends a BREAK signal to the modem port. _F_i_l_e _T_r_a_n_s_f_e_r_s When transferring files using the XMODEM protocol, the file mode is specified in the upload/download command. A TEXT mode transfer enables translation of the transmitted or received file to support CP/M and MS-DOS end-of-line characters. When transmitting a file using TEXT mode, all newlines are converted to carriage-return/newline sequences. When receiving a file using TEXT mode, all carriage-return/newline sequences are converted to just a newline. A BINARY mode transfer transmits the file "as is" without any such conversion. When transferring files using CompuServe B-Plus protocol, the format of the file is specified by the host. An ASCII mode will force xxxxcccc to per- form TEXT mode translation; a BINARY mode will not do any translation. This means that, in either direction, a BINARY mode will send bytes "as is", whereas in ASCII mode, an incoming file will always be stripped of end-of-line carriage-returns, while an ASCII file being uploaded may or may not have carriage-returns added after each newline, depending on the "on" or "off" setting of the "cr" option. When using either the "%t" (take) command, an XMODEM receive command, or a CompuServe B-Plus download command, xxxxcccc will check if the file name you specify already exists on your system, and ask for an OK to overwrite the file, or for an alternative name. In the CompuServe case, there will also be an option to "Resume" a download. If the CRC check- sum of the bytes that you already have in the file matches CompuServe's checksum on the the same initial bytes in its version of the file, file transfer will proceed from that point onwards. This saves connect time when a very large download has been interrupted during a prior session. Script-driven file transfers using the CompuServe B-Plus protocol are more or less built into the xxxxcccc script language, since during 'waitfor' processing, a file transfer request from the modem port will trigger a B-Plus transfer if the "cis" mode is set. The difficulty in performing such transfers isn't in the transfer itself, but rather in the maneuvering required to get into position to transfer the correct file, and is something that probably only experienced script writers should wrestle with. However, if we assume that in the midst of a script, you've reached a point where you can issue a "download" command to Com- puServe, for instance a "Disposition" prompt during a File Library "BROWSE" command, and you want to download the present file, which is "XCALL.C" on CompuServe, and "xcall.c" does not exist in your current working directory, you'd use the following sequence of script commands to do it: set cis on # can't do auto file B-Plus transfer otherwise transmit "dow^M" pause 2 # wait for CIS to display protocol menu transmit "2^M" # B-Plus is number 2 on that menu transmit "xcall.c^M" # "file name for your computer:" waitfor "Disposition" During the final "waitfor" processing, the CompuServe ENQ character will be recognized and the transfer will proceed automatically. Then 'waitfor' will continue waiting for the "Disposition" prompt, after which your script can proceed. The same sort of thing can be done with file uploads, but once again, the difficulty isn't with the transfer, but rather with setting things up so that the transfer will be requested at the correct place. A shell script, cccciiiissssddddoooowwwwnnnnllllooooaaaadddd provided with the distribution, can automatically retrieve a single file from a CompuServe library. For XMODEM, YMODEM, and ZMODEM transfers via scripts, there's no mechanism built into the xxxxcccc script language to use the built-in, 128- byte-packet XMODEM in xxxxcccc. Instead, we strongly recommend that you obtain Chuck Forsberg's excellent, shareware utility called "RZSZ", which can handle XMODEM, XMODEM-1K, YMODEM, and ZMODEM transfers and which can be used from within xxxxcccc with the 'pipe' command, or from com- mand mode with the '$' command, or using the examples under the _b_i_n_d__s_c_r_i_p_t command above. _D_e_b_u_g_g_i_n_g There are three varieties of debugging in xxxxcccc. The script command (set debug "on" or set debug "off") will control echoing of each line of a script to the screen. If the program was compiled with DEBUG set to 1 in xc.h, all screen output will be captured in a file called _d_e_b_u_g._l_o_g in the current directory, providing that it exists before entering xxxxcccc,,,, and providing that output is not being diverted to a current capture file. The _d_e_b_u_g._l_o_g file is overwritten each time xxxxcccc is run. If you forgot to turn on capturing, if the program was compiled with DEBUG set to 1, and if _d_e_b_u_g._l_o_g exists, all is not lost: your session is recorded in _d_e_b_u_g._l_o_g. Note that capturing to files is turned off when exiting terminal mode, and this includes running the built-in B+ or XMODEM protocols. Finally, in the xcb+.c module, there is a CIS_DEBUG definition line which is normally commented out. If this definition is uncommented, then a B+ transfer will record every byte in a file called _x_c._l_o_g. This file is created if needed, in the current directory, and overwrit- ten on each run of xxxxcccc. Exit Codes 0000 Successful, uneventful completion. 1111 Error in command-line arguments. 2222 Failure in forking to execute a command or run a shell. 3333 No modem port specified on the command line, or contained in the environment variable MODEM. 4444 Inability to create a LCK..file for the specified port. 5555 Inability to open the specified port. 6666 No environment variable TERM has been set. 7777 No entry for the current TERM setting in /etc/termcap. 8888 Problem caused by the 'ungetty' program. Copyright XXXXcccc and its source files and sample scripts and manual page are Copy- right 1993 by Jean-Pierre Radley. Permission is granted to the public to use this code in any manner, without any warranty, implied or otherwise, of fitness for a particular purpose. By virtue of a restriction previously placed upon all code derivative from xxxxccccoooommmmmmmm, the xxxxcccc code and associated files may not be sold by anyone to anyone, nor incorporated into any product that is not also free. It's OK to transfer them for free. Authors This manual page was written by Fred Buck (1989) and Jean-Pierre Radley (1990, 1991, 1992, 1993). XXXXcccc itself is the product of many synergistic wise minds. See the README document. Version This edition of the manual is for XC version 4.3 JPRadley 11 Sep 1993.